package com.apikey.auth.service;

import com.apikey.auth.entity.Application;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;
import java.util.Optional;

/**
 * API Key申请服务接口
 * 提供申请相关的业务逻辑
 *
 * @author API Key Framework
 * @version 1.0
 */
public interface ApplicationService {

    /**
     * 提交API Key申请
     *
     * @param phoneNumber    手机号
     * @param verifyPassword 验证密码（可选）
     * @param fingerprint    浏览器指纹
     * @param remark         申请说明
     * @return 申请记录
     */
    Application submitApplication(String phoneNumber, String verifyPassword, String fingerprint, String remark);

    /**
     * 根据手机号和验证密码查询申请状态
     *
     * @param phoneNumber    手机号
     * @param verifyPassword 验证密码
     * @return 申请记录列表
     */
    List<Application> queryApplicationByPhone(String phoneNumber, String verifyPassword);

    /**
     * 根据浏览器指纹查询申请状态
     *
     * @param fingerprint 浏览器指纹
     * @return 申请记录列表
     */
    List<Application> queryApplicationsByFingerprint(String fingerprint);

    /**
     * 根据ID查询申请记录
     *
     * @param id 申请ID
     * @return 申请记录
     */
    Optional<Application> findById(Long id);

    /**
     * 获取待审核的申请列表
     *
     * @param pageable 分页参数
     * @return 待审核申请分页结果
     */
    Page<Application> getPendingApplications(Pageable pageable);

    /**
     * 获取所有申请列表
     *
     * @param pageable 分页参数
     * @return 申请分页结果
     */
    Page<Application> getAllApplications(Pageable pageable);

    /**
     * 根据状态查询申请列表
     *
     * @param status   申请状态
     * @param pageable 分页参数
     * @return 申请分页结果
     */
    Page<Application> getApplicationsByStatus(Application.Status status, Pageable pageable);

    /**
     * 根据手机号查询申请记录
     *
     * @param phoneNumber 手机号
     * @return 申请记录列表
     */
    List<Application> findByPhoneNumber(String phoneNumber);

    /**
     * 根据审核人查询申请记录
     *
     * @param reviewer 审核人
     * @param pageable 分页参数
     * @return 申请分页结果
     */
    Page<Application> findByReviewer(String reviewer, Pageable pageable);

    /**
     * 根据时间范围查询申请记录
     *
     * @param startTime 开始时间
     * @param endTime   结束时间
     * @param pageable  分页参数
     * @return 申请分页结果
     */
    Page<Application> findByTimeRange(LocalDateTime startTime, LocalDateTime endTime, Pageable pageable);

    /**
     * 统计不同状态的申请数量
     *
     * @return 状态统计Map
     */
    Map<Application.Status, Long> getStatusStatistics();

    /**
     * 获取最近的申请记录
     *
     * @param limit 限制数量
     * @return 最近申请列表
     */
    List<Application> getRecentApplications(int limit);

    /**
     * 检查手机号是否有待审核或已通过的申请
     *
     * @param phoneNumber 手机号
     * @return 是否存在
     */
    boolean hasActiveApplicationByPhone(String phoneNumber);

    /**
     * 检查浏览器指纹是否有待审核或已通过的申请
     *
     * @param fingerprint 浏览器指纹
     * @return 是否存在
     */
    boolean hasActiveApplicationByFingerprint(String fingerprint);

    /**
     * 验证申请参数
     *
     * @param phoneNumber    手机号
     * @param verifyPassword 验证密码
     * @param fingerprint    浏览器指纹
     * @throws IllegalArgumentException 参数验证失败时抛出
     */
    void validateApplicationParams(String phoneNumber, String verifyPassword, String fingerprint);

    /**
     * 验证查询参数
     *
     * @param phoneNumber    手机号
     * @param verifyPassword 验证密码
     * @throws IllegalArgumentException 参数验证失败时抛出
     */
    void validateQueryParams(String phoneNumber, String verifyPassword);
}